Formatted Error Messages

This section discusses the TAPIERROR_FORMATMESSAGE() macro. This macro generates an identifier for standard TAPI error message text strings that can be obtained by Win32 applications using the Win32 FormatMessage() function.

This mechanism should be used only for displaying information on errors for which the application has no defined method of recovery (that is, unexpected or internal errors). In most cases (unlike the simplified example below), it is desirable to include additional text informing the user of actions the application will take (or the user should take) as a result of the unhandled error.

If the application gets an error result from any TAPI function, the error value can be passed through the TAPIERROR_FORMATMESSAGE() macro, which in turn generates the real value to be passed to FormatMessage(). FormatMessage() produces an error string corresponding to the error in a buffer. For example:

lResult = lineClose(hLine);

if (lResult < 0)

{ 

        FormatMessage(FORMAT_MESSAGE_FROM_HMODULE,

                    (LPCVOID)GetModuleHandle( TAPI32.DLL ),

                    TAPIERROR_FORMATMESSAGE(lResult),

                    0,

                    (LPTSTR)pBuf,

                    BUFSIZE,

                    NULL);

        MessageBox(hWnd,pBuf, TAPI ERROR ,MB_OK);

}